fig-financial-payments-b2b-xapi

Idempotency ensures that repeating the same API request — due to retries, timeouts, or network issues — does not result in duplicated operations or inconsistent payment states.

This mechanism is mandatory for all POST operations that create or trigger payment intents.

Concept

In simple terms:

Same request, same key → same result.
Same key, different request → conflict.

Each POST request must include an Idempotency-Key header, which uniquely identifies the operation being performed.

When the same key is received again:

• If the request body (ciphertext) is identical, the API returns the same response (safe retry).
• If the body differs, the API returns HTTP 409 Conflict to signal a potential duplication.

Encryption and Idempotency

Because this API uses AES-256/GCM with random Initialization Vectors (IVs), encrypting the same JSON data twice will result in two completely different ciphertexts.

Crucial Rule for Retries:

When retrying a request, you must resend the exact same ciphertext, IV, and AuthTag that were generated for the initial attempt. Do not re-encrypt the payload before retrying, as this will change the request body and trigger a 409 Conflict.

Header Specification

Recommendation: Use a new UUID v4 for every distinct payment intent request.

Behavior Example

1. First Request

The client generates the payload, encrypts it, and sends the ciphertext.

POST /intents/mbway
Host: api.fidelidade-financial.com
Idempotency-Key: 7d0f7e4e-6fcb-4b74-befc-d5f3b77b2f47
X-IV: uS9fK2d... (Base64)
X-AuthTag: pT5jL8... (Base64)
Content-Type: text/plain

BEm45DWVy4/7cVsrEgGP6XZGaCnZUcLotXgu70lXXFbeKSak1QMPKejnZ17yFgLmAJscuAf4o7Y=

Response (201 Created)

{
  "id": "SR29667_yMpWnf7Vl2CXFBQkF",
  "status": "pending",
  "links": {
"self": "/intents/SR29667_yMpWnf7Vl2CXFBQkF",
"status": "/intents/SR29667_yMpWnf7Vl2CXFBQkF/status"
  }
}

The system successfully created the payment intent and returned a unique ID.

If the same request is resent using the same Idempotency-Key and the exact same encrypted payload, the system will respond with the exact same response, ensuring that no duplicate transactions are created.

Safe Retries

Transient network errors, timeouts, or gateway interruptions can occasionally cause uncertainty about whether a payment request was processed successfully.

To prevent accidental duplicate payments, clients must always retry using the same Idempotency-Key when re-submitting a previously failed or timed-out request.

Critical Requirement for Encrypted Flows:

When retrying, you must send the exact same ciphertext, IV, and AuthTag used in the original attempt.

Do not re-encrypt the payload (which would generate a new IV).

Do not change the payload content.

When the same key and payload are received:

• The backend detects the replay.
• The API returns the exact same response as the original request.
• No duplicate operations or payment intents are created.

2. Retry Request (Identical Payload)

Request

POST /intents/mbway
Host: api.fidelidade-financial.com
Idempotency-Key: 7d0f7e4e-6fcb-4b74-befc-d5f3b77b2f47
X-IV: uS9fK2d...
X-AuthTag: pT5jL8...
Content-Type: text/plain

BEm45DWVy4/7cVsrEgGP6XZGaCnZUcLotXgu70lXXFbeKSak1QMPKejnZ17yFgLmAJscuAf4o7Y=

Response (201 Created)

    {
  "id": "SR29667_yMpWnf7Vl2CXFBQkF",
  "status": "pending",
  "links": {
    "self": "/intents/SR29667_yMpWnf7Vl2CXFBQkF",
    "status": "/intents/SR29667_yMpWnf7Vl2CXFBQkF/status"
  }
}

The system recognizes the Idempotency-Key and returns the same response as the original request without creating a new payment intent.

3. Retry with Different Payload (Conflict)

If the client attempts to reuse an Idempotency-Key with different data OR if the client re-encrypts the same data (generating a new random IV), the binary payload will differ.

Request

POST /intents/mbway
Host: api.fidelidade-financial.com
Idempotency-Key: 7d0f7e4e-6fcb-4b74-befc-d5f3b77b2f47
X-IV: NEW_GENERATED_IV...
X-AuthTag: NEW_TAG...
Content-Type: text/plain

DifferentCiphertext+XZGaCnZUcLotXgu70lXXFbeKSak1QMPKejnZ17yFg...

Response (409 Conflict)

{
  "errorCode": 409,
  "correlationId": "b8c6d0c0-81c1-11f0-9c0a-005056b539d8",
  "timeStamp": "2025-08-25T15:01:23Z",
  "description": "Conflict",
  "detailedDescription": "Idempotency key already used with a different request payload (or different encryption IV).",
  "externalError": ""
}

Implementation Guidelines

1. Generate Unique Keys: Always use a new UUID v4 for each distinct payment intent. Avoid reusing keys across unrelated requests to prevent conflicts.
2. Store Idempotency Keys: Clients should store the Idempotency-Key alongside the request data (including the specific IV and AuthTag used) to ensure safe retries in case of network issues.
3. Handle 409 Conflicts: If a 409 Conflict is received, verify the request payload. If the intent is to create a new payment, generate a new Idempotency-Key and retry.
4. Timeout Handling: Set appropriate retry timeouts (e.g., exponential backoff) to avoid overwhelming the API during transient failures.
5. Validate Responses: Always check the response status and payload to confirm the operation's success or handle errors appropriately.

Best Practices

• Use HTTPS: Ensure all API requests are made over secure HTTPS connections.
• Log Requests: Log the Idempotency-Key and response details for debugging and auditing purposes.
• Monitor Conflicts: Track 409 Conflict errors to identify potential issues in client retry logic or payload generation.
• Test Retries: Simulate network failures in a staging environment to verify that your client handles idempotency correctly.